home *** CD-ROM | disk | FTP | other *** search
/ Compendium Deluxe 1 / LSD Compendium Deluxe 1.iso / a / programming / arexx / rxser502.lha / rexxserdev.doc < prev    next >
Encoding:
Text File  |  1994-06-12  |  8.5 KB  |  227 lines
  1.                   Documentation for rexxserdev.library
  2.  
  3. copyright © 1993       by Joseph M. Stivaletta        All rights reserved.
  4. --------------------------------------------------------------------------
  5.  
  6. Version 5.02 fixes a couple of very nasty bugs.
  7.  
  8. Version 5.00 fixed bug in write and immediate IO request block.  Added read
  9. buffer parameter to the SerSetParms function.
  10.  
  11. Version 4.00 removed the dependency on arp.library and added a OS 2.04
  12. dependency.  This version will not work with prior versions of the
  13. Operating system.
  14.  
  15. Version 3.00 of my serial device function library for ARexx.  In this version
  16. I only disabled the version check for rexxsyslib.library.
  17.  
  18. Version 2.00 added support for multiple serial devices.  This was a major
  19. change over version 1.08.  Most functions now required a device handle
  20. for proper operation.
  21.  
  22. This library no longer uses ARP functions.  You should place my library into
  23. your LIBS: directory.  To use the Arexx serial device library, you must add it
  24. to the global library list using the either the addlib() function or the
  25. rxlib() command.
  26.  
  27. The current version number of this library is 5 and the query function offset
  28. is -30.  examples follow:
  29.  
  30.    addlib( 'rexxserdev.library', 0, -30, 5 )
  31.    rxlib rexxserdev.library 0 -30 5
  32.  
  33.  
  34. The rexxserdev.library was written to provide an easy to use interface
  35. between ARexx programs and any Amiga serial device.  The serial device
  36. will be opened as shared so take care when accessing that serial device
  37. from more than one application.  All I/O requests to the serial device are
  38. synchronous not asynchronous.  Therefore, a call to a function will not
  39. return to the application until that function is completed.  Due to the
  40. synchronous nature of the library functions the SerStart() and SerStop()
  41. functions may not work as designed for write calls.  The actual effect
  42. of these calls has yet to be determined.  At the current time I still have
  43. not implemented SerStart() and SerStop().
  44.  
  45. ==========================================================================
  46.                            Using the functions
  47.  
  48.  
  49. SerOpen()
  50. Usage: deviceHandle = SerOpen(deviceName,unitNumber)
  51. Opens the serial device and allocates the I/O requests and reply ports.
  52. Example:
  53.          dh = SerOpen( 'serial.device', 1 )      ==> a unique number
  54.  
  55.  
  56. SerClose()
  57. Usage: boolean = SerClose(deviceHandle)
  58. Closes the serial device and deallocates the I/O requests and reply ports.
  59. Example:
  60.          say SerClose( dh )     ==> 1
  61.  
  62.  
  63. SerClear()
  64. Usage: boolean = SerClear(deviceHandle)
  65. Clears the internal read buffer.
  66. Example:
  67.          say SerClear( dh )     ==> 1
  68.  
  69.  
  70. SerFlush()
  71. Usage: boolean = SerFlush(deviceHandle,{'R' | 'W'})
  72. Aborts all queued I/O requests in either the read or write request queue.
  73. Example:
  74.          say SerFlush( dh, 'R' )    ==> 1
  75.  
  76.  
  77. SerRead()
  78. Usage: charsRcvd = SerRead(deviceHandle,buffer,length)
  79. Read a number of characters from the serial port.  The number of characters
  80. read is specified by length.  The buffer is an internal read buffer supplied
  81. by the calling ARexx program.  This buffer is for use by the
  82. rexxserdev.library and not by the ARexx application.
  83. Example:
  84.          block = allocmem( 20 )
  85.          addr = c2d( block )
  86.          say SerRead( dh, addr, 20 )    ==> A string of 20 characters
  87.  
  88.  
  89. SerReset()
  90. Usage: boolean = SerReset(deviceHandle)
  91. Reinitializes the serial device to it's default state.
  92. Example:
  93.          say SerReset( dh )     ==> 1
  94.  
  95.  
  96. SerStart()
  97. Usage: boolean = SerStart(deviceHandle,{'R' | 'W'})
  98. Restarts reading or writing stopped by a previous SerStop() function.  Not
  99. yet implemented.
  100. Examples:
  101.          say SerStart( dh, 'W' )     ==> 1
  102.  
  103.  
  104. SerStop()
  105. Usage: boolean = SerStop(deviceHandle,{'R' | 'W'})
  106. Stops the currently executing read or write command.  Not yet implemented.
  107. Example:
  108.          say SerStop( dh, 'R' )      ==> 1
  109.  
  110.  
  111. SerWrite()
  112. Usage: boolean = SerWrite(deviceHandle,buffer,length)
  113. Sends the characters in the buffer to the serial port.
  114. Example:
  115.          text = 'send stuff out port'
  116.          say SerWrite( dh, text, length( text ) )     ==> 1
  117.  
  118.  
  119. SerBreak()
  120. Usage: boolean = SerBreak(deviceHandle)
  121. Sends a break signal.
  122. Examples:
  123.          say SerBreak( dh )      ==> 1
  124.  
  125.  
  126. SerQuery()
  127. Usage: status = SerQuery(deviceHandle)
  128. Returns status of the serial device.  The first substring indicates the
  129. validity of the rest of the string.  0 indicates that an error was returned
  130. from the query command and no additional information is contained within
  131. the status string.  1 indicates that the call was successful and the string
  132. contains two more substrings.  The second substring is the number in decimal
  133. ASCII of the number of characters currently in the internal read buffer.
  134. The third substring is the status word in decimal ASCII it is defined as
  135. follows:
  136.             Bit no.     Meaning of Bit
  137.  
  138.             0-2         Reserved
  139.             3           DSR - Data Set Ready (bit = 0)
  140.             4           CTS - Clear To Send (bit = 0)
  141.             5           DCD - Data Carrier Detect (bit = 0)
  142.             6           RTS - Ready To Send (bit = 0)
  143.             7           DTR - Data Terminal Ready (bit = 0)
  144.             8           Read buffer overflow (bit = 1)
  145.             9           Break signal sent (bit = 1)
  146.             10          Break signal received (bit = 1)
  147.             11          Transmit XOFF (bit = 1)
  148.             12          Received XOFF (bit = 1)
  149.             13-15       Reserved
  150. Examples:
  151.          say SerQuery( dh )   ==> 1 23 0
  152.                                   | |  +--> Status bits
  153.                                   | +-----> Number of characters received
  154.                                   +-------> Validity of status information
  155.  
  156.  
  157. SerSetParms()
  158. Usage: boolean = SerSetParms(deviceHandle,baud,databits,paritybits,
  159.                              stopbits,[flowCtl],[brkTime],[rbuffer])
  160. Sets the serial device parameters defined below.  The optional brkTime
  161. parameter is not yet implemented.  I have not incorporated SERF_RAD_BOOGIE
  162. so take care when using very high baud rates.  If the flowCtl parameter is
  163. not supplied, the serial port will default to Xon/Xoff flow control.
  164.  
  165. baud = allowed range is from 110 to 29,200
  166. databits = allowed range from 1 to 8
  167. paritybits = {'N' | 'E' | 'O' | 'M' | 'S'}
  168.               'N' = No parity
  169.               'E' = Even parity
  170.               'O' = Odd parity
  171.               'M' = Mark parity
  172.               'S' = Space parity
  173. stopbits = {'1' | '2'}
  174. flowCtl = {'0' | '1'}
  175.            '0' = Disable Xon/Xoff flow control
  176.            '1' = Enable Xon/Xoff flow control
  177.           the default is enabled Xon/Xoff flow control
  178. brkTime = duration of break signal in microseconds; the default value is
  179.           250,000 microseconds.
  180. rbuffer = recommended size of the buffer that the serial port should
  181.           allocate for incoming data.  For some hardware the buffer size
  182.           will not be adjustable.  The default buffer size is 1000 bytes.
  183.  
  184. Examples:
  185.          say SerSetParms( dh, 9600, 7, e, 1, 0 )      ==> 1
  186.  
  187.  
  188. ==========================================================================
  189.                               User rights
  190.  
  191. I do not guarantee that this software library is free from bugs.  It has
  192. been used for a few years and has proven useful.  I will try to keep
  193. future versions downwardly compatible but make no promises that it will
  194. not change slightly based on user feedback.
  195.  
  196. These programs are not public domain but can be freely distributed as long as
  197. this document is included.  I retain the rights to their use.  This means
  198. that they cannot be sold for profit by anyone without my written permission.
  199.  
  200.  
  201. ==========================================================================
  202.                             Disclaimer BS
  203.  
  204. If this software, blows up your machine, melts you hard drive, causes
  205. loss of hair, mental anguish, mental disorders, or marital difficuties
  206. ending in divorce, I will not be held liable.  I make no warranties, either
  207. expressed or implied, with respect to the programs described herein,
  208. their quality, performance, or fitness for any particular purpose.  These
  209. programs are distributed "AS IS." The entire risk as to their quality and
  210. performance is with the user.  I promise only to fix the bugs and to
  211. improve and enhance the code as I deem able in my spare time.
  212.  
  213.  
  214. ==========================================================================
  215.                             Problem reporting
  216.  
  217. If you find any errors or have any problems, your flames can reach me
  218. at the following locations:
  219.  
  220. CompuServe:
  221. PIN: 72155,516
  222.  
  223. Bix:
  224. ID: jstivaletta
  225.                                           Joseph M. Stivaletta
  226.                                           23 March 1993
  227.